<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="created" content="2018-10-23T06:18:10.521000000">
    <meta name="changed" content="2018-10-23T06:18:42.262000000">
    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    <meta http-equiv="Content-Language" content="en">
    <title>
      assembler
    </title>
    <link rel="stylesheet" type="text/css" href="../../style.css">
  </head>
  <body>
    <div class="maindiv">
      <h1>
        Introduction
      </h1>
      <p>
        The build in assembler of logisim-evolution supports besides the instructions provided by the used processor several features as described in this help page.The assembler uses syntax highlighting and error detection. Furthermore it translates the instructions into byte-code that can be executed by the processor. Although the structure of the assembler would allow to write out an elf-file this feature is not yet implemented.
      </p>
      <h1>
        Using the GUI
      </h1>
      <p>
        When opening the assembler you are presented with a new window as shown below:
      </p>
      <p>
        <img src="../../../../img-guide/assembler_gui.png" alt="assembler" title="The assembler gui">
      </p>
      <p>
        The GUI consists of three components:
      </p>
      <ol>
        <li>The tool bar which is on top of the editing area.
        </li>
        <li>The line indication bar with error indicators to the left of the editing area.
        </li>
        <li>The editing area.
        </li>
      </ol>
      <h2>
        The toolbar
      </h2>
      <p>
        The toolbar provides the main functions of the assembler by use of several icons:
      </p>
      <p>
        <img class="notscal" src="../../../../img-guide/assembler_load.png" alt="load"> This icon activates the loading of an assembly file into the editing area. The load function can also be activated by the keyboard shortcut (Ctrl-L).
      </p>
      <p>
        <img class="notscal" src="../../../../img-guide/assembler_save.png" alt="save" title="assembler save"> This icon activates the saving of the current contents in the editing area. The save function can also be activated by the keyboard shortcut (Ctrl-S).
      </p>
      <p>
        <img class="notscal" src="../../../../img-guide/assembler_save_as.png" alt="save as" > This icon activates the save-as function of the current contents in the editing area. The save-as function has no keyboard shortcut.
      </p>
      <p>
        <img class="notscal" src="../../../../img-guide/assembler_assemble.png" alt="assemble" > This icon activates the assemble function of the current contents in the editing area. The assemble function cal also be activated by the keyboard shortcut (ALT-A).
      </p>
      <p>
        <img class="notscal"src="../../../../img-guide/assembler_prev_error.png" alt="previous error" > This icon jumps to an error detected before the current cursor position. This function is also available by the keyboard shortcut (Ctrl-P).
      </p>
      <p>
        <img class="notscal"src="../../../../img-guide/assembler_next_error.png" alt="next error"> This icon jumps to an error detected after the current cursor position. This function is also available by the keyboard shortcut (Ctrl-N).
      </p>
      <p>
        <img class="notscal"src="../../../../img-guide/assembler_run.png" alt="run"> This icon activated the assemble function and, when no errors are detected, loads the program into memory. The run function can also be activated by the keyboard shortcut (ALT-R).
      </p>
      <p>
        <img class="notscal"src="../../../../img-guide/assembler_help.png" alt="help"> This icon show this help screen.
      </p>
      <p>
        To the right of the toolbar the current line of the cursor and the total number of lines in the editing area are displayed. In case this indicator lights up yellow there are changes detected in the editing area.
      </p>
      <h2>
        The line indicator bar
      </h2>
      <p>
        The line indicator bar hold, besides the current line number, also the error indicator icons. Hovering over the error indicator bar will show (one of) the error(s) detected on the given line in the editing area.
      </p>
      <h2>
        The editing area
      </h2>
      <p>
        The editing area contains all the code you might want to use. In case your code contains errors (after activating the assemble or run function) the errors will be displayed by an error icon in the line indicator bar and a small red line underneath the text causing the problem. hovering over this text with the mouse will display the error cause. It is important to note that, when multiple errors are present in one line, only one will be displayed by the error marker in the line indicator bar. Furthermore, in case of calculations (like in line 17 in the above showed image) it might be that only the 8 is marked instead of the complete calculation.
      </p>
      <h1>
        Using calculations
      </h1>
      <p>
        The assembler supports two types of calculations:
      </p>
      <ol>
        <li>Program counter (PC) relative calculations
        </li>
        <li>Absolute calculations
        </li>
      </ol>
      <h2>
        Program counter relative calculations
      </h2>
      <p>
        In case an address is required relative to the current program counter these calculations can be performed by using the reserved register <b>pc</b>. Also the usage of labels and constants are allowed in these calculations.
      </p>
      <p>
        Examples: <b>pc</b>+8 , <b>pc</b>-0x40, mylabel-<b>pc</b>, etc.
      </p>
      <h2>
        Absolute calculations
      </h2>
      <p>
        In absolute calculations a constant value is calculated. To perform absolute calculations labels and constants are allowed.
      </p>
      <h2>
        Calculation types
      </h2>
      <p>
        Following calculation types are supported:
      </p>
      <ul>
        <li>+ =&gt; Addition
        </li>
        <li>- =&gt; Subtraction
        </li>
        <li>* =&gt; Multiplication
        </li>
        <li>/ =&gt; Integer division
        </li>
        <li>% =&gt; Integer remainder
        </li>
        <li>&lt;&lt; =&gt; Shift left
        </li>
        <li>&gt;&gt; =&gt; Shift right
        </li>
      </ul><em>Note:</em> Currently the parentheses are not supported.<br>
      <h2>
        Calculation order
      </h2>
      <p>
        <i><b>Important:</b></i> For the moment the calculations are performed left-to-right independent of the hierarchy of the operator!
      </p>
      <p>
        This means:
      </p>
      <p>
        5+10*2 is calculated as (5+10)*2 = 30
      </p>
      <p>
        10*2+5 is calculated as (10*2)+5 = 25
      </p>
      <p>
        It is on the todo list to improve this poor calculation support.
      </p>
      <h1>
        Using macros
      </h1>
      <p>
        The build in assembler supports macros. The syntax for a macro is:
      </p>
      <p>
        <strong>.macro</strong> <em>&lt;name&gt;</em> <em>&lt;nr_of_variables&gt;</em>
      </p>
      <p>
        <em>&lt;BODY&gt;</em>
      </p>
      <p>
        <strong>.endm</strong>
      </p>
      <p>
        A macro definition needs two parameters:
      </p>
      <ol>
        <li>
          <em>&lt;name&gt;</em> This parameter is the name of the macro to be used in the rest of your program.
        </li>
        <li>
          <em>&lt;nr_of_variables&gt;</em> This parameter specifies the number of variables that are used inside the macro. This parameter should be a positive integer value (e.g. 0,1,2,....)
        </li>
      </ol>
      <h2>
        Allowed constructs inside a macro
      </h2>
      <p>
        Inside a macro you can use only instructions, labels, calculations, and calls to other macros. It is important to note that labels defined inside the &lt;BODY&gt; of a macro are local to the macro and cannot be referenced outside the macro.
      </p>
      <h2>
        Using variables inside a macro
      </h2>
      <p>
        If the parameter <em>&lt;nr_of_variables&gt;</em> is a number bigger than 0, the macro must be called with this number of values. Each of this values can be referenced inside a macro with the indicator @<em>&lt;x&gt;</em> where <em>&lt;x&gt;</em> is a number. Hence @1 references parameter 1, @2 parameter 2, etc.
      </p>
      <h2>
        Using macro calls inside a macro
      </h2>
      <p>
        Macros allow to call other macros, however there are two restrictions:
      </p>
      <ol>
        <li>A macro cannot call itself; recursive macros are not supported.
        </li>
        <li>Two macros cannot call each other; circular calls are not supported.
        </li>
      </ol>
      <h1>
        Assembler directives
      </h1>
      <p>
        There are several directives supported as described below.
      </p>
      <h2>
        Labels
      </h2>
      <p>
        Labels can be used by the syntax <em>&lt;name&gt;</em><strong>:</strong> The <em>&lt;name&gt;</em> must start with a letter and may contain letters (a..z;A..Z), numbers (0..9), and underscores (_). Note that labels specified inside a macro are local to the macro. All other labels are global (hence a global label can be referenced inside a macro).
      </p>
      <h2>
        Named constants
      </h2>
      <p>
        Named constants can be defined by the syntax <strong>.equ</strong> <em>&lt;name&gt;</em> <em>&lt;value&gt;</em>. The <em>&lt;name&gt;</em> parameter must start with a letter and may contain letters (a..z;A..Z), numbers (0..9), and underscores (_). The <em>&lt;value&gt;</em> field can contain a number or a calculation.
      </p>
      <h2>
        Sections
      </h2>
      <p>
        You can divide your program into sections by using <strong>.section</strong> <em>&lt;name&gt;</em>. The <em>&lt;name&gt;</em> parameter must start with a letter and may contain letters (a..z;A..Z), numbers (0..9), and underscores (_). There are four predefined section names being <strong>.text</strong>, <strong>.data</strong>, <strong>.rodata</strong>, <strong>.bss</strong>. These do not require the <strong>.section</strong> keyword in front of them.
      </p>
      <h2>
        Remarks
      </h2>
      <p>
        Remarks are supported by placing a <strong>#</strong> in front of them and extend until the end of the line. Multi line remarks can be realized by putting in front of each line the <strong>#</strong>.
      </p>
      <h2>
        Strings
      </h2>
      <p>
        Strings can be specified by <strong>.string "</strong><em>&lt;str&gt;</em><strong>"</strong>, <strong>.ascii"</strong><em>&lt;str&gt;</em><strong>"</strong>, or <strong>.asciz"</strong><em>&lt;str&gt;</em><strong>"</strong>. The <em>&lt;str&gt;</em> can contain any contents and may be multiple lines. Following escape codes can be used:
      </p>
      <ol>
        <li>\n -&gt; insert a new-line character.
        </li>
        <li>\" -&gt; insert a double quote.
        </li>
        <li>\t -&gt; insert a tab-character.
        </li>
        <li>\r -&gt; insert a carriage return character.
        </li>
        <li>\f -&gt; insert a form feed.
        </li>
        <li>\\ -&gt; insert a back slash.
        </li>
      </ol>
      <p>
        Both <strong>.string</strong> and <strong>.asciz</strong> will automatically insert a zero character at the end of the string.
      </p>
      <h2>
        Memory addresses
      </h2>
      <p>
        By default the assembler will start at memory address 0x00000000. To be able to change the current memory address the directive <strong>.org</strong> <em>&lt;address&gt;</em> can be used, where the <em>&lt;address&gt;</em> is a value within a 32-bit address space. <em>Note:</em> only inter-section overlap will be checked by the assembler. If inside a section an address is specified that is already being occupied, the values are overwritten.
      </p>
      <h2>
        Constants
      </h2>
      <p>
        There are several ways to fill the memory with constant values. Besides from the byte-based way, all the others use a little-endian storage method, meaning that the least significant byte is stored at the lowest memory address, and the most significant byte at the highest memory address. The supported directives are:
      </p>
      <ol>
        <li>
          <strong>.byte</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]</em> This directive stores the value(s) interpreted as bytes one after the other into memory.
        </li>
        <li>
          <strong>.half</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]<br></em> <strong>.2byte</strong> <em><em>&lt;value1&gt;[,&lt;value2&gt;,...]<br></em></em> <strong>.short</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]</em> These directives store the value(s) interpreted as 16-bit values one after the other into memory.
        </li>
        <li>
          <strong>.word</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]<br></em> <strong>.4byte</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]<br></em> <strong>.long</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]</em> These directives store the value(s) interpreted as 32-bit values one after the other into memory.
        </li>
        <li>
          <strong>.dword</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]<br></em> <strong>.8byte</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]<br></em> <strong>.quad</strong> <em>&lt;value1&gt;[,&lt;value2&gt;,...]</em> These directives store the value(s) interpreted as 64-bit values one after the other into memory.
        </li>
      </ol>
    </div>
  </body>
</html>
